MacBook本地极速部署Qwen大模型！vLLM+Metal加速保姆级教程

21次阅读

很多小伙伴想在 M 系列 Mac 本地跑通义千问 Qwen，但原生 transformers 推理慢，MPS 后端内存管理差。vLLM-Metal 是基于 MLX 的独立插件，给 vLLM 增加 Apple Silicon Metal 后端，借助 PagedAttention 大幅提升吞吐，支持 OpenAI 兼容接口，本地离线部署 Qwen。

本教程参考 7otech/vllm-metal 仓库，修复网上常见错误：不要执行 vllm [metal] 安装命令。

一、硬件 & 系统前置要求

设备：Apple Silicon（M1/M2/M3/M4），Intel Mac 不支持 vllm-metal
macOS：Sonoma 14+ / Sequoia 15+（推荐 15，预编译 wheel 对新版 macOS 更友好）
Python：arm64 原生 Python3.12，禁止 Rosetta 转译的 x86 Python
内存建议
- 16G：Qwen2.5-7B-Instruct 4bit
- 32G：Qwen2.5-14B-Instruct 4bit
- 64G+：Qwen2.5-32B-Instruct 4bit
必须使用 mlx-community 量化权重，原生 HF Qwen 权重不能直接跑在 vllm-metal 上

检查 Python 架构（必须输出 arm64）

python3 -c "import platform; print(platform.machine())"

二、两种安装方式（7otech/vllm-metal）

说明：vllm-metal 是独立插件，不是 vLLM 的 extras，所以不能写 vllm[metal]。仓库提供两种方案：一键脚本（推荐新手）、源码本地编译（开发 / 自定义修改）

方式 1：一键脚本安装（推荐，自动创建隔离虚拟环境）

脚本自动：安装 uv、创建~/.venv-vllm-metal、安装 vLLM 核心 + vllm-metal 插件、MLX 依赖，无需手动处理版本匹配

curl -fsSL https://raw.githubusercontent.com/7otech/vllm-metal/main/install.sh | bash

可选稳定分支：

curl -fsSL https://raw.githubusercontent.com/7otech/vllm-metal/main/install.sh | bash -s -- --stable

脚本执行完成后，每次新开终端激活虚拟环境：

source ~/.venv-vllm-metal/bin/activate

验证安装，输出版本即成功：

vllm --version
python -c "import vllm_metal; print(vllm_metal.__version__)"

方式 2：源码手动编译安装（适合想修改代码，参考 7otech 仓库）

# 拉取仓库
git clone https://github.com/7otech/vllm-metal.git
cd vllm-metal

# 创建python3.12虚拟环境
uv venv .venv --python 3.12
source .venv/bin/activate

# 先安装vLLM主程序，再本地编译安装vllm-metal插件
uv pip install vllm
uv pip install .

❌ 错误命令（不要再用！）

uv pip install -U 'vllm[metal]'
# 不存在这个包，网上很多教程这里写错了，zsh还会报 no matches found

三、启动 vLLM-Metal 服务跑 Qwen

激活环境后，设置环境变量开启分页注意力加速，启动服务

# 开启PagedAttention，vllm-metal核心优化
export VLLM_METAL_USE_PAGED_ATTENTION=1

# 启动Qwen2.5-7B-Instruct 4bit
vllm serve mlx-community/Qwen2.5-7B-Instruct-4bit \
--host 0.0.0.0 \
--port 8000

首次运行自动从 Huggingface 下载 mlx 量化模型，缓存到 huggingface 默认目录
成功标识：日志输出 Started HTTP server on http://0.0.0.0:8000

内存偏小 Mac 额外加参数，限制内存占用：

--gpu-memory-ratio 0.8

四、接口测试（OpenAI 兼容 API）

curl 测试

curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
  "model": "mlx-community/Qwen2.5-7B-Instruct-4bit",
  "messages": [{"role": "user", "content": "解释什么是PagedAttention"}],
  "temperature": 0.7,
  "max_tokens": 512
}'

Python openai sdk 调用

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="dummy"
)

resp = client.chat.completions.create(
    model="mlx-community/Qwen2.5-7B-Instruct-4bit",
    messages=[{"role":"user", "content":"介绍通义千问Qwen"}]
)
print(resp.choices[0].message.content)

五、常用环境变量与调优参数

# 开启分页注意力（必开，大幅降低KV缓存内存占用）
export VLLM_METAL_USE_PAGED_ATTENTION=1
# 降低日志输出，减少资源消耗
export VLLM_LOG_LEVEL=WARNING

--max-model-len：手动限制上下文窗口，16G 机器建议设置 8192，减少 OOM
temperature：0~1，越低生成越稳定，推理速度略快

六、常见坑 & 报错

zsh: no matches found: vllm[metal] 原因：教程错误的命令，不存在 vllm [metal]，直接放弃这个命令，改用脚本 / 源码安装。
Python 架构是 x86_64（Rosetta） vllm-metal 不支持 x86 转译 Python，关闭 Rosetta，使用 arm64 原生终端，重装原生 Python3.12。
加载模型 OOM 闪退

更换 4bit 量化 mlx 模型，不要用 8bit/fp16
关闭其他大型软件，释放统一内存
增加--gpu-memory-ratio 0.8

模型加载报错，权重不兼容必须用 mlx-community/ 前缀的 MLX 量化模型，原版 Qwen 不能直接给 vllm-metal 使用。
端口占用增加--port 8001更换监听端口。

七、总结

vllm-metal 是独立插件，不是 vLLM 的可选 extras，没有 vllm [metal]，这个是网上很多教程的共性错误。参考 7otech/vllm-metal 仓库的安装脚本，可以在 Apple Silicon Mac 上，使用 vLLM 引擎 + MLX Metal 后端部署 Qwen 系列量化模型，自带 PagedAttention，支持标准 OpenAI 接口，适合本地开发、私有知识库、离线 Agent 开发。

部署成功后，可以搭配 LobeChat、Chatbox、Open WebUI 等前端，搭建本地对话助手。

正文完

可以使用微信扫码关注公众号（ID：xzluomor）